FORMAT: 1A
HOST: https://history.avwx.rest/api

# AVWX History

The AVWX History API provides searchable access to past reports.

## Authentication

AVWX uses bearer tokens for user authentication. Create an account at [account.avwx.rest](https://account.avwx.rest) to generate your token and include it in your requests.

The API looks for tokens in two places:

- `"Authorization"` header. The token value can have any prefix (`"TOKEN abcde"`, `"BEARER abcde"`, etc) or just the token value itself
- `"?token=abcde"` URL parameter

The header value will supercede the URL parameter if both are found. All examples in the documentation use the header method.

All endpoints in the AVWX History API require an Enterprise level plan to access.

## Report History

The METAR report cache goes back to **January 1st, 2016** while other report types have not yet been backfilled. If there is interest in backfilling the historic record for TAF and other report types, let me know.

Reports are added by the main API whenever a new report is requested. A backfill script is run every day at 1:00 UTC to maintain a complete record. Requesting data within the last two days will include recent reports merged from NOAA, so it may take a little longer to fulfill that request.


## History [/{report_type}/{ident}{?recent,date,parse,format}]

Returns historic reports from a specific station. Currently supports METAR and TAF.

- Calls with `recent` but not `date` return the most recent n number of reports up to a max of 48 in one call
- Calls with `date` but not `recent` return all reports from that date
- Calls with both `recent` and `date` return the most recent n number of reports no more recent than the given date

+ Parameters
    + report_type: `metar` (string) - Weather report type
        + supported: metar, taf
    + ident: `KJFK` (string) - ICAO station ident
    + date: `2020-01-01` (optional) - ISO date yyyy-mm-dd
    + recent: 2 (number, optional) - Number of recent reports up to 48. Will return all reports on a date if not provided
    + parse (boolean, optional) - Parse the reports or just return sanitized strings
        + Default: true
    + format (optional) - Desired response format
        + supported: json, xml, yaml
        + Default: `json`

### Get Reports by Station [GET]

This example shows the two most recent METAR reports for JKF International in New York City.

+ Request

    + Headers
    
            Authorization: Token my_secret_api_token

+ Response 200 (application/json)

        {
            "meta": "2019-12-02T06:08:47.779080+00:00Z",
            "results": [
                {
                    "altimeter": {
                        "repr": "2946",
                        "value": 29.46,
                        "spoken": "two nine point four six"
                    },
                    "clouds": [
                        {
                            "repr": "OVC010",
                            "type": "OVC",
                            "altitude": 10,
                            "modifier": null,
                            "direction": null
                        }
                    ],
                    "flight_rules": "MVFR",
                    "other": [
                        "-RA",
                        "BR"
                    ],
                    "sanitized": "KJFK 020551Z 04019G27KT 6SM -RA BR OVC010 04/04 A2946 RMK AO2 PK WND 04032/0512 RAE32B38 SLP977 931000 P0001 60010 T00390039 10050 20039 58006 $",
                    "visibility": {
                        "repr": "6",
                        "value": 6,
                        "spoken": "six"
                    },
                    "wind_direction": {
                        "repr": "040",
                        "value": 40,
                        "spoken": "zero four zero"
                    },
                    "wind_gust": {
                        "repr": "27",
                        "value": 27,
                        "spoken": "two seven"
                    },
                    "wind_speed": {
                        "repr": "19",
                        "value": 19,
                        "spoken": "one nine"
                    },
                    "raw": "KJFK 020551Z 04019G27KT 6SM -RA BR OVC010 04/04 A2946 RMK AO2 PK WND 04032/0512 RAE32B38 SLP977 931000 P0001 60010 T00390039 10050 20039 58006 $",
                    "station": "KJFK",
                    "time": {
                        "repr": "020551Z",
                        "dt": "2019-12-02T05:51:00Z"
                    },
                    "remarks": "RMK AO2 PK WND 04032/0512 RAE32B38 SLP977 931000 P0001 60010 T00390039 10050 20039 58006 $",
                    "dewpoint": {
                        "repr": "04",
                        "value": 4,
                        "spoken": "four"
                    },
                    "remarks_info": {
                        "dewpoint_decimal": {
                            "repr": "3.9",
                            "value": 3.9,
                            "spoken": "three point nine"
                        },
                        "temperature_decimal": {
                            "repr": "3.9",
                            "value": 3.9,
                            "spoken": "three point nine"
                        }
                    },
                    "runway_visibility": [],
                    "temperature": {
                        "repr": "04",
                        "value": 4,
                        "spoken": "four"
                    },
                    "wind_variable_direction": []
                },
                {
                    "altimeter": {
                        "repr": "2947",
                        "value": 29.47,
                        "spoken": "two nine point four seven"
                    },
                    "clouds": [
                        {
                            "repr": "OVC010",
                            "type": "OVC",
                            "altitude": 10,
                            "modifier": null,
                            "direction": null
                        }
                    ],
                    "flight_rules": "MVFR",
                    "other": [
                        "BR"
                    ],
                    "sanitized": "KJFK 020532Z 04022G32KT 6SM BR OVC010 04/04 A2947 RMK AO2 PK WND 04032/0512 RAE32 P0000 T00440039 $",
                    "visibility": {
                        "repr": "6",
                        "value": 6,
                        "spoken": "six"
                    },
                    "wind_direction": {
                        "repr": "040",
                        "value": 40,
                        "spoken": "zero four zero"
                    },
                    "wind_gust": {
                        "repr": "32",
                        "value": 32,
                        "spoken": "three two"
                    },
                    "wind_speed": {
                        "repr": "22",
                        "value": 22,
                        "spoken": "two two"
                    },
                    "raw": "KJFK 020532Z 04022G32KT 6SM BR OVC010 04/04 A2947 RMK AO2 PK WND 04032/0512 RAE32 P0000 T00440039 $",
                    "station": "KJFK",
                    "time": {
                        "repr": "020532Z",
                        "dt": "2019-12-02T05:32:00Z"
                    },
                    "remarks": "RMK AO2 PK WND 04032/0512 RAE32 P0000 T00440039 $",
                    "dewpoint": {
                        "repr": "04",
                        "value": 4,
                        "spoken": "four"
                    },
                    "remarks_info": {
                        "dewpoint_decimal": {
                            "repr": "3.9",
                            "value": 3.9,
                            "spoken": "three point nine"
                        },
                        "temperature_decimal": {
                            "repr": "4.4",
                            "value": 4.4,
                            "spoken": "four point four"
                        }
                    },
                    "runway_visibility": [],
                    "temperature": {
                        "repr": "04",
                        "value": 4,
                        "spoken": "four"
                    },
                    "wind_variable_direction": []
                }
            ]
        }